home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
IRIX Base Documentation 1998 November
/
IRIX 6.5.2 Base Documentation November 1998.img
/
usr
/
share
/
catman
/
u_man
/
cat3
/
Tk
/
parseargv.z
/
parseargv
Wrap
Text File
|
1998-10-30
|
25KB
|
463 lines
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk))))
NNNNAAAAMMMMEEEE
Tk_ParseArgv - process command-line options
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
int
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv(_i_n_t_e_r_p, _t_k_w_i_n, _a_r_g_c_P_t_r, _a_r_g_v, _a_r_g_T_a_b_l_e, _f_l_a_g_s)
AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
Tcl_Interp *_i_n_t_e_r_p (in) Interpreter to use for returning
error messages.
Tk_Window _t_k_w_i_n (in) Window to use when arguments specify
Tk options. If NULL, then no Tk
options will be processed.
int _a_r_g_c_P_t_r (in/out) Pointer to number of arguments in
argv; gets modified to hold number
of unprocessed arguments that remain
after the call.
char **_a_r_g_v (in/out) Command line arguments passed to main
program. Modified to hold
unprocessed arguments that remain
after the call.
Tk_ArgvInfo *_a_r_g_T_a_b_l_e (in) Array of argument descriptors,
terminated by element with type
TK_ARGV_END.
int _f_l_a_g_s (in) If non-zero, then it specifies one or
more flags that control the parsing
of arguments. Different flags may be
OR'ed together. The flags currently
defined are
TK_ARGV_DONT_SKIP_FIRST_ARG,
TK_ARGV_NO_ABBREV,
TK_ARGV_NO_LEFTOVERS, and
TK_ARGV_NO_DEFAULTS.
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv processes an array of command-line arguments according to a
table describing the kinds of arguments that are expected. Each of the
arguments in _a_r_g_v is processed in turn: if it matches one of the entries
in _a_r_g_T_a_b_l_e, the argument is processed according to that entry and
discarded. The arguments that do not match anything in _a_r_g_T_a_b_l_e are
copied down to the beginning of _a_r_g_v (retaining their original order) and
returned to the caller. At the end of the call TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv sets
*_a_r_g_c_P_t_r to hold the number of arguments that are left in _a_r_g_v, and
_a_r_g_v[*_a_r_g_c_P_t_r] will hold the value NULL. Normally, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv assumes
that _a_r_g_v[_0] is a command name, so it is treated like an argument that
PPPPaaaaggggeeee 1111
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk))))
doesn't match _a_r_g_T_a_b_l_e and returned to the caller; however, if the
TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in _f_l_a_g_s then _a_r_g_v[_0] will be
processed just like the other elements of _a_r_g_v.
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv normally returns the value TCL_OK. If an error occurs while
parsing the arguments, then TCL_ERROR is returned and TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will
leave an error message in _i_n_t_e_r_p->_r_e_s_u_l_t in the standard Tcl fashion. In
the event of an error return, *_a_r_g_v_P_t_r will not have been modified, but
_a_r_g_v could have been partially modified. The possible causes of errors
are explained below.
The _a_r_g_T_a_b_l_e array specifies the kinds of arguments that are expected;
each of its entries has the following structure:
ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt {
cccchhhhaaaarrrr*_k_e_y;
iiiinnnntttt _t_y_p_e;
cccchhhhaaaarrrr*_s_r_c;
cccchhhhaaaarrrr*_d_s_t;
cccchhhhaaaarrrr*_h_e_l_p;
}}}} TTTTkkkk____AAAArrrrggggvvvvIIIInnnnffffoooo;;;;
The _k_e_y field is a string such as ``-display'' or ``-bg'' that is
compared with the values in _a_r_g_v. _T_y_p_e indicates how to process an
argument that matches _k_e_y (more on this below). _S_r_c and _d_s_t are
additional values used in processing the argument. Their exact usage
depends on _t_y_p_e, but typically _s_r_c indicates a value and _d_s_t indicates
where to store the value. The cccchhhhaaaarrrr **** declarations for _s_r_c and _d_s_t are
placeholders: the actual types may be different. Lastly, _h_e_l_p is a
string giving a brief description of this option; this string is printed
when users ask for help about command-line options.
When processing an argument in _a_r_g_v, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv compares the argument
to each of the _k_e_y's in _a_r_g_T_a_b_l_e. TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv selects the first
specifier whose _k_e_y matches the argument exactly, if such a specifier
exists. Otherwise TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv selects a specifier for which the
argument is a unique abbreviation. If the argument is a unique
abbreviation for more than one specifier, then an error is returned. If
there is no matching entry in _a_r_g_T_a_b_l_e, then the argument is skipped and
returned to the caller.
Once a matching argument specifier is found, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv processes the
argument according to the _t_y_p_e field of the specifier. The argument that
matched _k_e_y is called ``the matching argument'' in the descriptions
below. As part of the processing, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv may also use the next
argument in _a_r_g_v after the matching argument, which is called ``the
following argument''. The legal values for _t_y_p_e, and the processing that
they cause, are as follows:
PPPPaaaaggggeeee 2222
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk))))
TTTTKKKK____AAAARRRRGGGGVVVV____EEEENNNNDDDD
Marks the end of the table. The last entry in _a_r_g_T_a_b_l_e must have
this type; all of its other fields are ignored and it will never
match any arguments.
TTTTKKKK____AAAARRRRGGGGVVVV____CCCCOOOONNNNSSSSTTTTAAAANNNNTTTT
_S_r_c is treated as an integer and _d_s_t is treated as a pointer to an
integer. _S_r_c is stored at *_d_s_t. The matching argument is
discarded.
TTTTKKKK____AAAARRRRGGGGVVVV____IIIINNNNTTTT
The following argument must contain an integer string in the format
accepted by ssssttttrrrrttttoooollll (e.g. ``0'' and ``0x'' prefixes may be used to
specify octal or hexadecimal numbers, respectively). _D_s_t is treated
as a pointer to an integer; the following argument is converted to
an integer value and stored at *_d_s_t. _S_r_c is ignored. The matching
and following arguments are discarded from _a_r_g_v.
TTTTKKKK____AAAARRRRGGGGVVVV____FFFFLLLLOOOOAAAATTTT
The following argument must contain a floating-point number in the
format accepted by ssssttttrrrrttttoooollll. _D_s_t is treated as the address of an
double-precision floating point value; the following argument is
converted to a double-precision value and stored at *_d_s_t. The
matching and following arguments are discarded from _a_r_g_v.
TTTTKKKK____AAAARRRRGGGGVVVV____SSSSTTTTRRRRIIIINNNNGGGG
In this form, _d_s_t is treated as a pointer to a (char *);
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv stores at *_d_s_t a pointer to the following argument, and
discards the matching and following arguments from _a_r_g_v. _S_r_c is
ignored.
TTTTKKKK____AAAARRRRGGGGVVVV____UUUUIIIIDDDD
This form is similar to TK_ARGV_STRING, except that the argument is
turned into a Tk_Uid by calling TTTTkkkk____GGGGeeeettttUUUUiiiidddd. _D_s_t is treated as a
pointer to a Tk_Uid; TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv stores at *_d_s_t the Tk_Uid
corresponding to the following argument, and discards the matching
and following arguments from _a_r_g_v. _S_r_c is ignored.
TTTTKKKK____AAAARRRRGGGGVVVV____CCCCOOOONNNNSSSSTTTT____OOOOPPPPTTTTIIIIOOOONNNN
This form causes a Tk option to be set (as if the ooooppppttttiiiioooonnnn command had
been invoked). The _s_r_c field is treated as a pointer to a string
giving the value of an option, and _d_s_t is treated as a pointer to
the name of the option. The matching argument is discarded. If
_t_k_w_i_n is NULL, then argument specifiers of this type are ignored (as
if they did not exist).
TTTTKKKK____AAAARRRRGGGGVVVV____OOOOPPPPTTTTIIIIOOOONNNN____VVVVAAAALLLLUUUUEEEE
This form is similar to TK_ARGV_CONST_OPTION, except that the value
of the option is taken from the following argument instead of from
_s_r_c. _D_s_t is used as the name of the option. _S_r_c is ignored. The
matching and following arguments are discarded. If _t_k_w_i_n is NULL,
then argument specifiers of this type are ignored (as if they did
PPPPaaaaggggeeee 3333
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk))))
not exist).
TTTTKKKK____AAAARRRRGGGGVVVV____OOOOPPPPTTTTIIIIOOOONNNN____NNNNAAAAMMMMEEEE____VVVVAAAALLLLUUUUEEEE
In this case the following argument is taken as the name of a Tk
option and the argument after that is taken as the value for that
option. Both _s_r_c and _d_s_t are ignored. All three arguments are
discarded from _a_r_g_v. If _t_k_w_i_n is NULL, then argument specifiers of
this type are ignored (as if they did not exist).
TTTTKKKK____AAAARRRRGGGGVVVV____HHHHEEEELLLLPPPP
When this kind of option is encountered, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv uses the _h_e_l_p
fields of _a_r_g_T_a_b_l_e to format a message describing all the valid
arguments. The message is placed in _i_n_t_e_r_p->_r_e_s_u_l_t and TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv
returns TCL_ERROR. When this happens, the caller normally prints
the help message and aborts. If the _k_e_y field of a TK_ARGV_HELP
specifier is NULL, then the specifier will never match any
arguments; in this case the specifier simply provides extra
documentation, which will be included when some other TK_ARGV_HELP
entry causes help information to be returned.
TTTTKKKK____AAAARRRRGGGGVVVV____RRRREEEESSSSTTTT
This option is used by programs or commands that allow the last
several of their options to be the name and/or options for some
other program. If a TTTTKKKK____AAAARRRRGGGGVVVV____RRRREEEESSSSTTTT argument is found, then
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv doesn't process any of the remaining arguments; it
returns them all at the beginning of _a_r_g_v (along with any other
unprocessed arguments). In addition, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv treats _d_s_t as the
address of an integer value, and stores at *_d_s_t the index of the
first of the TTTTKKKK____AAAARRRRGGGGVVVV____RRRREEEESSSSTTTT options in the returned _a_r_g_v. This allows
the program to distinguish the TTTTKKKK____AAAARRRRGGGGVVVV____RRRREEEESSSSTTTT options from other
unprocessed options that preceded the TTTTKKKK____AAAARRRRGGGGVVVV____RRRREEEESSSSTTTT.
TTTTKKKK____AAAARRRRGGGGVVVV____FFFFUUUUNNNNCCCC
For this kind of argument, _s_r_c is treated as the address of a
procedure, which is invoked to process the following argument. The
procedure should have the following structure:
iiiinnnntttt
_f_u_n_c(_d_s_t, _k_e_y, _n_e_x_t_A_r_g)
cccchhhhaaaarrrr *_d_s_t;
cccchhhhaaaarrrr *_k_e_y;
cccchhhhaaaarrrr *_n_e_x_t_A_r_g;
{
}
The _d_s_t and _k_e_y parameters will contain the corresponding fields
from the _a_r_g_T_a_b_l_e entry, and _n_e_x_t_A_r_g will point to the following
argument from _a_r_g_v (or NULL if there aren't any more arguments left
in _a_r_g_v). If _f_u_n_c uses _n_e_x_t_A_r_g (so that TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv should discard
it), then it should return 1. Otherwise it should return 0 and
TTTTkkkkPPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will process the following argument in the normal
PPPPaaaaggggeeee 4444
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk))))
fashion. In either event the matching argument is discarded.
TTTTKKKK____AAAARRRRGGGGVVVV____GGGGEEEENNNNFFFFUUUUNNNNCCCC
This form provides a more general procedural escape. It treats _s_r_c
as the address of a procedure, and passes that procedure all of the
remaining arguments. The procedure should have the following form:
iiiinnnntttt
_g_e_n_f_u_n_c(_d_s_t, _i_n_t_e_r_p, _k_e_y, _a_r_g_c, _a_r_g_v)
cccchhhhaaaarrrr *_d_s_t;
TTTTccccllll____IIIInnnntttteeeerrrrpppp *_i_n_t_e_r_p;
cccchhhhaaaarrrr *_k_e_y;
iiiinnnntttt _a_r_g_c;
cccchhhhaaaarrrr **_a_r_g_v;
{
}
The _d_s_t and _k_e_y parameters will contain the corresponding fields
from the _a_r_g_T_a_b_l_e entry. _I_n_t_e_r_p will be the same as the _i_n_t_e_r_p
argument to TTTTccccllll____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv. _A_r_g_c and _a_r_g_v refer to all of the
options after the matching one. _G_e_n_f_u_n_c should behave in a fashion
similar to TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv: parse as many of the remaining arguments
as it can, then return any that are left by compacting them to the
beginning of _a_r_g_v (starting at _a_r_g_v[0]). _G_e_n_f_u_n_c should return a
count of how many arguments are left in _a_r_g_v; TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will
process them. If _g_e_n_f_u_n_c encounters an error then it should leave
an error message in _i_n_t_e_r_p->_r_e_s_u_l_t, in the usual Tcl fashion, and
return -1; when this happens TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will abort its processing
and return TCL_ERROR.
FFFFLLLLAAAAGGGGSSSS
TTTTKKKK____AAAARRRRGGGGVVVV____DDDDOOOONNNNTTTT____SSSSKKKKIIIIPPPP____FFFFIIIIRRRRSSSSTTTT____AAAARRRRGGGG
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv normally treats _a_r_g_v[_0] as a program or command name,
and returns it to the caller just as if it hadn't matched _a_r_g_T_a_b_l_e.
If this flag is given, then _a_r_g_v[_0] is not given special treatment.
TTTTKKKK____AAAARRRRGGGGVVVV____NNNNOOOO____AAAABBBBBBBBRRRREEEEVVVV
Normally, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv accepts unique abbreviations for _k_e_y values
in _a_r_g_T_a_b_l_e. If this flag is given then only exact matches will be
acceptable.
TTTTKKKK____AAAARRRRGGGGVVVV____NNNNOOOO____LLLLEEEEFFFFTTTTOOOOVVVVEEEERRRRSSSS
Normally, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv returns unrecognized arguments to the caller.
If this bit is set in _f_l_a_g_s then TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will return an error
if it encounters any argument that doesn't match _a_r_g_T_a_b_l_e. The only
exception to this rule is _a_r_g_v[_0], which will be returned to the
caller with no errors as long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't
specified.
PPPPaaaaggggeeee 5555
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk))))
TTTTKKKK____AAAARRRRGGGGVVVV____NNNNOOOO____DDDDEEEEFFFFAAAAUUUULLLLTTTTSSSS
Normally, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv searches an internal table of standard
argument specifiers in addition to _a_r_g_T_a_b_l_e. If this bit is set in
_f_l_a_g_s, then TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will use only _a_r_g_T_a_b_l_e and not its default
table.
EEEEXXXXAAAAMMMMPPPPLLLLEEEE
Here is an example definition of an _a_r_g_T_a_b_l_e and some sample command
lines that use the options. Note the effect on _a_r_g_c and _a_r_g_v; arguments
processed by TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv are eliminated from _a_r_g_v, and _a_r_g_c is updated
to reflect reduced number of arguments.
/*
* Define and set default values for globals.
*/
int debugFlag = 0;
int numReps = 100;
char defaultFileName[] = "out";
char *fileName = defaultFileName;
Boolean exec = FALSE;
/*
* Define option descriptions.
*/
Tk_ArgvInfo argTable[] = {
{"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
"Turn on debugging printfs"},
{"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
"Number of repetitions"},
{"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
"Name of file for output"},
{"x", TK_ARGV_REST, (char *) NULL, (char *) &exec,
"File to exec, followed by any arguments (must be last argument)."},
{(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL,
(char *) NULL}
};
main(argc, argv)
int argc;
char *argv[];
{
...
if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
fprintf(stderr, "%s\n", interp->result);
exit(1);
}
/*
* Remainder of the program.
*/
PPPPaaaaggggeeee 6666
TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk))))
}
Note that default values can be assigned to variables named in _a_r_g_T_a_b_l_e:
the variables will only be overwritten if the particular arguments are
present in _a_r_g_v. Here are some example command lines and their effects.
prog -N 200 infile # just sets the numReps variable to 200
prog -of out200 infile # sets fileName to reference "out200"
prog -XN 10 infile # sets the debug flag, also sets numReps
In all of the above examples, _a_r_g_c will be set by TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv to 2,
_a_r_g_v[0] will be ``prog'', _a_r_g_v[1] will be ``infile'', and _a_r_g_v[2] will be
NULL.
KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
arguments, command line, options
PPPPaaaaggggeeee 7777
